Skip Headers

Oracle® Database PL/SQL Packages and Types Reference 10g Release 2 (10.2) Part Number B14258-01 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next

# 165 UTL_DBWS

The `UTL_DBWS` package provides database web services.

This chapter contains the following topics:

- Using UTL_DBWS

  - Supported Keys and Default Settings for Standard Call Properties

- Summary of UTL_DBWS Subprograms

## Using UTL_DBWS

- Supported Keys and Default Settings for Standard Call Properties

### Supported Keys and Default Settings for Standard Call Properties

Table 165-1 Supported Keys and Default Settings for Standard Call Properties

Key | Explanation of Value, Default value
--- | ---
`'USERNAME'` | User name for authentication.
`'PASSWORD'` | Password for authentication.
`'ENCODINGSTYLE_URI'` | Encoding style specified as a namespace URI. The default value is the SOAP 1.1 encoding http://schemas.xmlsoap.org/soap/encoding/.
`'OPERATION_STYLE'` | Standard property for operation style. Set to '`RPC`' if the operation style is RPC, '`DOCUMENT`' if the operation style is document.
`'SESSION_MAINTAIN'` | This boolean property is used by a service client to indicate whether or not it wants to participate in a session with a service endpoint.If this property is set to '`TRUE`', the service client indicates that it wants the session to be maintained. If set to '`FALSE`', the session is not maintained. The default value for this property is '`FALSE`'
`'SOAPACTION_USE'` | This boolean property indicates whether or not SOAPAction is to be used. The default value of this property is '`FALSE`'.
`'SOAPACTION_URI'` | Indicates the SOAPAction URI if the `SOAPACTION_USE` property is set to '`TRUE'`

## Summary of UTL_DBWS Subprograms

Table 165-2 UTL_DBWS Subprograms

Subprogram | Description
--- | ---
CREATE_CALL Function | Creates a Call instance
CREATE_SERVICE Function | Creates a Service instance
GET_IN_PARAMETER_TYPES Function | Lists the XML type of the input parameters of the Call that is returned
GET_OUT_PARAMETER_TYPES Function | Lists the XML type of the output parameters of the Call that is returned
GET_OUTPUT_VALUES Function | Obtains the output arguments after a Call invocation
GET_PORTS Function | Lists the qualified names of all of the ports in a service
GET_PROPERTY Function | Returns the value of a particular property on a Call
GET_RETURN_TYPE Function | Lists the XML type that is returned by the given Call
GET_SERVICES Function | Lists the qualified names of the services defined in a WDSL document
INVOKE Function | Invokes a specific operation using a synchronous request-response interaction mode
RELEASE_ALL_SERVICES Procedure | Releases all Service instances
RELEASE_CALL Procedure | Releases a particular Call instance
RELEASE_SERVICE Procedure | Releases a particular Service instance
REMOVE_PROPERTY Procedure | Clears the value of a particular property on a Call
SET_PROPERTY Procedure | Sets the value of a particular property on a Call

### CREATE_CALL Function

This procedure creates a Call instance.

Syntax

    UTL_DBWS.CREATE_CALL (
       service_handle    SERVICE,
       port_name         QNAME,
       operation_name    QNAME)
     RETURN CALL;

Parameters

Table 165-3 CREATE_CALL Function Parameters

Parameter | Description
--- | ---
`service_handle` | The Service instance to be called.
`port_name` | The `qualified name for the port. Use the first port if this is NULL`.
`operation_name` | The qualified name for the operation.

Return Values

Table 165-4 CREATE_CALL Return Values

Parameter | Description
--- | ---
`CALL` | Returns a handle to the Call instance.

### CREATE_SERVICE Function

This procedure creates a Service instance.

Syntax

    UTL_DBWS.CREATE_SERVICE(
       wsdl_document_location  URITYPE,
       service_name            QNAME)
      RETURN SERVICE;

Parameters

Table 165-5 CREATE_SERVICE Function Parameters

Parameter | Description
--- | ---
`wsdl_document_location` | The URL for the WSDL document location for the service
`service_name` | The qualified name for the service. Use the first service if this is `NULL`.

Return Values

Table 165-6 CREATE_SERVICE Return Values

Parameter | Description
--- | ---
`SERVICE` | Returns a handle to the Service instance.

### GET_IN_PARAMETER_TYPES Function

This procedure lists the XML type of the input parameters of the Call that is returned.

Syntax

    UTL_DBWS.GET_IN_PARAMETER_TYPES(
       call_handle    CALL)
     RETURN QNAME_LIST;

Parameters

Table 165-7 GET_IN_PARAMETER_TYPES Function Parameters

Parameter | Description
--- | ---
`call_handle` | The Service instance whose input types are returned.

Return Values

Table 165-8 GET_IN_PARAMETER_TYPES Function Return Values

Parameter | Description
--- | ---
`QNAME_LIST` | The list of the XML type of the input parameters of the Call that is returned.

### GET_OUT_PARAMETER_TYPES Function

This procedure lists the XML type of the output parameters of the Call that is returned.

Syntax

    UTL_DBWS.GET_OUT_PARAMETER_TYPES(
       call_handle    CALL)
     RETURN QNAME_LIST;

Parameters

Table 165-9 GET_OUT_PARAMETER_TYPES Function Parameters

Parameter | Description
--- | ---
`call_handle` | The Service instance whose output types are returned.

Return Values

Table 165-10 GET_OUT_PARAMETER_TYPES Function Return Values

Parameter | Description
--- | ---
`QNAME_LIST` | The list of the XML type of the input parameters of the Call that is returned.

### GET_OUTPUT_VALUES Function

This procedure obtains the output arguments after a Call invocation.

Syntax

    UTL_DBWS.GET_OUTPUT_VALUES(
       call_handle    CALL)
     RETURN ANYDATA_LIST;

Parameters

Table 165-11 GET_OUTPUT_VALUES Function Parameters

Parameter | Description
--- | ---
`call_handle` | The instance of the Call.

Return Values

Table 165-12 GET_OUTPUT_VALUES Function Return Values

Parameter | Description
--- | ---
`ANYDATA_LIST` | Returns the output arguments in order.

### GET_PORTS Function

This procedure lists the qualified names of all of the ports in a service.

Syntax

    UTL_DBWS.GET_PORTS(
       service_handle    SERVICE)
     RETURN QNAME_LIST;

Parameters

Table 165-13 GET_PORTS Function Parameters

Parameter | Description
--- | ---
`service_handle` | The service instance whose ports are returned

Return Values

Table 165-14 GET_PORTS Function Return Values

Parameter | Description
--- | ---
`QNAME_LIST` | Returns a list of the qualified names of all ports in a service

### GET_PROPERTY Function

This procedure returns the value of a particular property on a Call.

Syntax

    UTL_DBWS.GET_PROPERTY(
       call_handle    CALL,
       key            VARCHAR2)
      RETURN value VARCHAR2;

Parameters

Table 165-15 GET_PROPERTY Function Parameters

Parameter | Description
--- | ---
`call_handle` | The the instance of the Call.
`key` | The key for the property (see Using UTL_DBWS)

Return Values

Table 165-16 GET_PROPERTY Function Return Values

Parameter | Description
--- | ---
`value` | Returns the value of a particular property on a Call.

### GET_RETURN_TYPE Function

This procedure lists the XML type that is returned by the given Call.

Syntax

    UTL_DBWS.GET_RETURN_TYPE (
       call_handle    CALL)
     RETURN QNAME;

Parameters

Table 165-17 GET_RETURN_TYPE Function Parameters

Parameter | Description
--- | ---
`call_handle` | The Service instance whose return type is returned.

Return Values

Table 165-18 GET_RETURN_TYPE Function Return Values

Parameter | Description
--- | ---
`QNAME` | The type that is returned.

### GET_SERVICES Function

This function lists the qualified names of the services defined in a WDSL document.

Syntax

    UTL_DBWS.GET_SERVICES(
       wsdl_document_location  URITYPE)
     RETURN QNAME_LIST;

Parameters

Table 165-19 GET_SERVICES Function Parameters

Parameter | Description
--- | ---
`wsdl_document_location` | The Service instance whose return type is returned.

Return Values

Table 165-20 GET_SERVICES Function Return Values

Parameter | Description
--- | ---
`QNAME_LIST` | A list of the qualified names of the services defined in the WSDL document.

### INVOKE Function

This procedure invokes a specific operation using a synchronous request-response interaction mode.

Syntax

    UTL_DBWS.INVOKE(
       call_handle    CALL,
       input_params   ANYDATA_LIST)
     RETURN ANYDATA;

Parameters

Table 165-21 INVOKE Function Parameters

Parameter | Description
--- | ---
`call_handle` | The Service instance whose return type is returned.
`input_params` | The input parameters for this invocation.

Return Values

Table 165-22 INVOKE Function Return Values

Parameter | Description
--- | ---
`ANYDATA` | `Returns the return value or NULL`.

### RELEASE_ALL_SERVICES Procedure

This procedure releases all Service instances.

Syntax

    UTL_DBWS.RELEASE_ALL_SERVICES;

### RELEASE_CALL Procedure

This procedure releases a particular Call instance.

Syntax

    UTL_DBWS.RELEASE_CALL(
       call_handle    CALL);

Parameters

Table 165-23 RELEASE_CALL Procedure Parameters

Parameter | Description
--- | ---
`call_handle` | The call instance that is to be released.

### RELEASE_SERVICE Procedure

This procedure releases a particular Service instance.

Syntax

    UTL_DBWS.RELEASE_SERVICE (
       service_handle     SERVICE);

Parameters

Table 165-24 RELEASE_SERVICE Procedure Parameters

Parameter | Description
--- | ---
service_handle | The call instance that is to be released.

Usage Notes

This will implicitly release all Call instances that have been created for this Service instance.

### REMOVE_PROPERTY Procedure

This procedure clears the value of a particular property on a Call.

Syntax

    UTL_DBWS.REMOVE_PROPERTY(
       call_handle   CALL,
       key           VARCHAR2);

Parameters

Table 165-25 REMOVE_PROPERTY Procedure Parameters

Parameter | Description
--- | ---
`call_handle` | The call instance.
`key` | The key for the property (see Using UTL_DBWS).

### SET_PROPERTY Procedure

This procedure sets the value of a particular property on a Call.

Syntax

    UTL_DBWS.SET_PROPERTY(
       call_handle    CALL,
       key            VARCHAR2,
       value          VARCHAR2);

Parameters

Table 165-26 SET_PROPERTY Function Parameters

Parameter | Description
--- | ---
`call_handle` | The instance of the Call.
`key` | The key for the property (see Using UTL_DBWS).
`value` | The value for the property.